DOcumentation for stack filter; forgot to commit this yesterday.

diff --git a/gpsbabel/README b/gpsbabel/README
index 0d2a46d2947038dc49ad80b064fb9d262df15b64..5daf2b4a9fb783305c8c4e75f09dfd8a11c3b10a 100644 (file)
--- a/gpsbabel/README
+++ b/gpsbabel/README
@@ -810,6 +810,82 @@ DATA FILTERS
         to sort by geocaching.com waypoint ID's when the input comes
         from a GPX file that has GC numbers in it.
 
+    STACK
+ 
+        This filter is designed to solve advanced problems that involve
+        shuffling multiple lists of waypoints.  It has three distinct
+        sets of suboptions:
+ 
+        PUSH
+ 
+            Pushes the current list of waypoints onto the stack.  If
+            the 'copy' suboption is specified, a copy of the current
+            list is pushed onto the stack; otherwise, the current
+            list is cleared.
+                  -x stack,push
+                  -x stack,push,copy
+
+        POP
+
+            'Pops' the top list of waypoints off of the stack.  What is
+            done with that list depends on the suboption specified.  If
+            the 'append' suboption is specified, the top list of waypoints
+            from the stack is added to the end of the current list of
+            waypoints.  If the 'discard' option is specified, the top
+            list of waypoints is removed from the stack and discarded,
+            leaving the current list of waypoints unchanged.  If the
+            'replace' option is specified, or if no option is specified,
+            the top list of waypoints from the stack replaces the current
+            list of waypoints; the previous contents of the current list
+            are discarded.
+                  -x stack,pop 
+                  -x stack,pop,discard
+                  -x stack,pop,append
+
+        SWAP
+
+            Swaps the current list of waypoints with a list from the 
+            stack.  If no further options are specified, the current 
+            list is swapped with the top list on the stack.  If the 
+            'depth' option is specified, it indicates which item on 
+            the stack should be swapped.  
+                  -x stack,swap        
+                  -x stack,swap,depth=2 
+
+        The stack can be used in conjunction with other filters to 
+        implement a "union" or "logical or" functionality.  The basic
+        idea is to use the stack to store copies of the original list 
+        of waypoints, then use the 'swap' function to replace each copy
+        with a filtered list.  Finally, append all of the filtered lists
+        to create one big list, which is then output.  The following
+        example finds a list of all points that are either inside county A
+        or inside county B.  Any points that are inside both counties are
+        duplicated (but the duplicates can be removed with the DUPLICATE
+        filter; see above.)
+
+           gpsbabel -i gpx -f in.gpx \
+                    -x stack,push,copy \
+                    -x polygon,file=county_a.txt \    
+                    -x stack,swap \
+                    -x polygon,file=county_b.txt \
+                    -x stack,pop,append \
+                    -o gpx -F out.gpx
+
+        This example reads a large list of waypoints and extracts the
+        points within 20 miles of each of two cities, writing the 
+        waypoint descriptions into two different PalmDoc files and 
+        exporting all of the points to the GPS receiver:
+
+           gpsbabel -i gpx -f indiana.gpx \
+                    -x stack,push,copy \
+                    -x radius,lat=41.0765,lon=-85.1365,distance=20m \
+                    -o palmdoc,dbname=Fort\ Wayne -F fortwayne.pdb \
+                    -x stack,swap \
+                    -x radius,lat=39.7733,lon=-86.1433,distance=20m \
+                    -o palmdoc,dbname=Indianapolis -F indianapolis.pdb \
+                    -x stack,pop,append \
+                    -o magellan -F fwaind.wpt
+ 
 COMMON USAGE
 
        Invocation was meant to be flexible.   Unfortunately, that can